Skip to content

feat(autoconfigure): auto-configure OpenAPI / Swagger UI for the admin API#48

Merged
jlc488 merged 1 commit into
mainfrom
feat/openapi-swagger
Jun 1, 2026
Merged

feat(autoconfigure): auto-configure OpenAPI / Swagger UI for the admin API#48
jlc488 merged 1 commit into
mainfrom
feat/openapi-swagger

Conversation

@jlc488

@jlc488 jlc488 commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

What / 무엇

Adds OpenAPI / Swagger UI auto-configuration for the admin API — the "add the starter, nothing else" promise extended to API docs. Drop springdoc on the classpath and /swagger-ui + /v3/api-docs come up with no wiring, the admin API grouped; one property turns it off.

관리자 API용 OpenAPI / Swagger UI 자동 구성 추가 — "스타터만 추가" 철학을 API 문서까지. springdoc만 classpath에 있으면 설정 없이 /swagger-ui + /v3/api-docs가 뜨고 관리자 API가 그룹화됨. 프로퍼티 하나로 끔.

How / 어떻게

  • OpenApiAutoConfiguration@ConditionalOnClass(GroupedOpenApi) (springdoc는 compileOnly라 소비자가 추가해야 활성) + @ConditionalOnWebApplication(SERVLET) + @ConditionalOnProperty(devslab.kit.openapi.enabled, matchIfMissing=true). /admin/api/v1/**를 한 그룹으로 묶는 GroupedOpenApi와 기본 OpenAPI 문서(title/version) 제공 — 둘 다 @ConditionalOnMissingBean이라 소비자가 재정의 가능.
  • devslab.kit.openapi.enabled=false — 의존성 제거 없이 비활성화 (프로덕션에서 일반적).
  • SPRINGDOC_VERSION=3.0.3 — Spring Boot 4 / Spring Framework 7 라인 (2.8.x는 SB3 대상; Spring Boot BOM이 springdoc을 관리하지 않아 직접 핀). v3.0.3 릴리스가 Spring Boot 4.0.5 지원.
  • DevslabKitProperties.OpenApienabled / admin-group / title / version.

Tests / 테스트 (real HTTP + Testcontainers)

이게 "springdoc 3.0.x ↔ Spring Boot 4 Jackson 3" 우려가 우리 구성에선 문제없음을 증명:

  • OpenApiEndpointTests (3): /v3/api-docs → 200 + 유효 JSON(실제 직렬화 성공), 그룹 /v3/api-docs/admin/admin/api/v1 노출, /swagger-ui/index.html → 200 (admin security chain은 /admin/api/v1/**만 잡으므로 미차단).
  • OpenApiDisabledTests (1): enabled=false 시 admin 그룹 사라짐.

Verification / 검증

Local full ./gradlew build green — 44 tests, 0 failures; mkdocs build --strict clean.

Docs / 문서

README(.ko) Features + Configuration 표, docs/reference/configuration(.ko) 새 OpenAPI 섹션, CHANGELOG(.ko) Unreleased.

Note: this lands in Unreleased (post-0.1.0). It's a new minor feature → next tag would be 0.2.0.

…n API

Add the kit's documented promise to the API-docs surface too: drop springdoc on the
classpath and /swagger-ui + /v3/api-docs come up with no wiring, the admin API grouped,
and a single property turns it off.

- OpenApiAutoConfiguration: @ConditionalOnClass(GroupedOpenApi) so it's dormant until the
  consumer adds springdoc (declared compileOnly here), @ConditionalOnWebApplication(SERVLET),
  and @ConditionalOnProperty(devslab.kit.openapi.enabled, matchIfMissing=true) so
  `devslab.kit.openapi.enabled=false` disables it without removing the dependency (typical
  in production). Contributes a GroupedOpenApi pinned to /admin/api/v1/** and a default
  OpenAPI document (title/version); both @ConditionalOnMissingBean so a consumer can override.
- DevslabKitProperties: new OpenApi block (enabled / admin-group / title / version).
- gradle.properties: SPRINGDOC_VERSION=3.0.3 — the Spring Boot 4 / Spring Framework 7 line
  (2.8.x targets Spring Boot 3; the Spring Boot BOM does not manage springdoc). Consumed
  compileOnly by autoconfigure.
- sample-app: add springdoc-openapi-starter-webmvc-ui (a consumer opting in) so the
  end-to-end path is exercised.

Verified by sample-app integration tests over the real HTTP stack — this is what proves
the springdoc-3.0.x-on-Jackson-3 concern is a non-issue for our setup:
- OpenApiEndpointTests (3): /v3/api-docs returns 200 + valid JSON (real serialization),
  the admin group /v3/api-docs/admin lists /admin/api/v1, and /swagger-ui/index.html is
  200 (not blocked — the admin security chain only matches /admin/api/v1/**).
- OpenApiDisabledTests (1): enabled=false removes the admin group.

Docs: README(.ko) Features + Configuration tables, docs/reference/configuration(.ko) new
OpenAPI section, CHANGELOG(.ko) Unreleased. Full `./gradlew build` green (44 tests, 0
failures); mkdocs --strict clean.
@jlc488
jlc488 merged commit 8abc59d into main Jun 1, 2026
2 checks passed
@jlc488
jlc488 deleted the feat/openapi-swagger branch June 1, 2026 15:21
jlc488 added a commit that referenced this pull request Jun 1, 2026
…es (#49)

Prepare the 0.2.0 release (adds OpenAPI / Swagger UI auto-configuration, #48).

- CHANGELOG(.ko): promote the Unreleased OpenAPI entry to [0.2.0] — 2026-06-02.
- README(.ko): bump the install snippet to 0.2.0.
- docs/getting-started/installation(.ko): bump the dependency coordinates to 0.2.0
  and refresh the pre-1.0 note (0.1.0 is published now — "build from source to try
  unreleased changes" rather than "until 0.1.0 is published").

Historical/context mentions of 0.1.0 (the [0.1.0] changelog heading, "publishes
from 0.1.0 onward", roadmap) are left as-is. gradle.properties stays at -SNAPSHOT;
release.yml injects the tag version via -PVERSION (sibling pattern).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant